home *** CD-ROM | disk | FTP | other *** search
/ BCI NET 2 / BCI NET 2.iso / archives / programming / e / amigae31apart2.lha / Amiga_E_v3.1a / Src / Tools / EasyGUI / EasyGUI.doc < prev   
Encoding:
INI File  |  1992-09-02  |  7.3 KB  |  224 lines
  1. [Here's the new EasyGUI! it's still not completely done yet, but way
  2.  more finished than the v3.0a version.]
  3.  
  4.  
  5.                               Introducing:
  6.  
  7.  
  8.                              E A S Y G U I
  9.  
  10.  
  11.      An interface builder for E, with the following highlights:
  12.  
  13.     - It's totally Font-Sensitive
  14.     - It's Resizable
  15.     - It's Self-Organising, i.e. it arranges gadgets
  16.     - It's more StyleGuide compliant than your granny
  17.     - It's Fast and Flexible
  18.     - It's relatively small, needs no extra external libraries
  19.     - And above all: It's extremely easy to use!!!
  20.  
  21.      Bad Sides:
  22.  
  23.     - It lacks the full power/features of MUI/BGUI/Triton etc.
  24.  
  25.  
  26.  
  27. EasyGUI takes the form a module file that needs to be included into your
  28. E source. The most simple form of constructing a GUI consist of calling
  29. the function easygui() with a (possibly nested) E list which describes
  30. your GUI. just to show how Easy, try this source:
  31.  
  32.     MODULE 'tools/EasyGUI'
  33.     PROC main() IS easygui('um,...',[BUTTON,0,'Ok!'])
  34.  
  35. This'll open a window with just one gadget in it, and wait for the
  36. user to push it. If easygui() can't get what it wants, it'll start
  37. throwing around exceptions, so we'll probably need an exception
  38. handler to be able to inform the user properly (see below).
  39.  
  40. The first arg of easygui() is the window title, the second one is the
  41. GUI description. The form of these desciptions is quite simple: It's a
  42. list with as first element the type of gadget, the second is called an
  43. action value (more later), and the rest is gadget-specific.
  44.  
  45. To be able to build GUI's outof more components than just one gadget,
  46. one can group gadgets with a ROW and a COL list:
  47.  
  48. [COLS,
  49.   [BUTTON,1,'Ok'],
  50.   [BUTTON,0,'Cancel']
  51. ]
  52.  
  53. This'll create a new group, consisting of two gadgets next to each other.
  54. COLS and ROWS groups are like a single gadget, i.e. you can easily put them
  55. into other groups, to create GUI's of infinite complexity.
  56.  
  57. Other Grouping functions are EQCOLS and EQCOLS, which try to align gadgets
  58. in a group.
  59.  
  60. [BEVEL,a] will put a bevel box around a, whatever it is (a gadget, a group...),
  61. and BEVELR is the recessed version.
  62.  
  63. Other elements of groups are mostly gadgets, which have a specific #of
  64. arguments. [If the number of arguments is incorrect, EasyGUI will raise
  65. the "Egui" exception.]
  66.  
  67.  
  68. gadgets:
  69.  
  70. general format: [NAME,action,text,...]
  71. in {}: which direction it may resize.
  72. * = not implemented or things missing.
  73.  
  74. Each gadget shows the gadget template, explanation, the form of the
  75. actionfunction (explained below), and a typical example).
  76.  
  77.  
  78. [BUTTON,action,intext]
  79. buttonaction(info)
  80. example: [BUTTON,0,'Cancel']
  81.  
  82. [CHECK,action,righttext,checkedbool,lefttextbool]
  83. checkedbool = whether gadget should initially be check-marked
  84. checkaction(info,checkedbool)
  85. example: [CHECK,{case},'Ignore case',TRUE,FALSE]
  86.  
  87. [INTEGER,action,lefttext,num,relsize]
  88. num = initial value
  89. integeraction(info,newnum) {x}
  90. example: [INTEGER,{v},'int:',5,3]
  91.  
  92. [LISTV,action,textabove,relx,rely,execlist,readbool,selected]
  93. execlist = ptr to an execlist. (see tools/constructors.m)
  94. readbool = whether listview is read-only
  95. *selected = 0=none, 1=read, 2=strgad (fill in 0 for compat.)
  96. listviewaction(info,num_selected) {x,y}
  97. [LISTV,0,NIL,5,5,filenamelist,0,NIL]
  98.  
  99. [MX,action,abovetext,nil_term_elist,lefttextbool]
  100. mxaction(info,num_selected)
  101. example: [MX,{v},NIL,['One','Two','Three',NIL],FALSE]
  102.  
  103. [CYCLE,action,lefttext,nil_term_elist]
  104. cycleaction(info,num_selected)
  105. example: [CYCLE,{v},'choose:',['Yep','Nope',NIL]]
  106.  
  107. [PALETTE,action,lefttext,depth,relx,rely]
  108. depth = 1..8, number of bitplanes this color is for
  109. paletteaction(info,colour) {x,y}
  110. example: [PALETTE,{v},'color:',3,5,2]
  111.  
  112. [SCROLL,action,isvert,total,top,visible,relsize]
  113. total = resolution of scroller
  114. top = current top represented
  115. visible = current
  116. scolleraction(info,curtop) {x|y}
  117. example: [SCROLL,{v},FALSE,10,0,2,2]
  118.  
  119. [SLIDE,action,lefttext,isvert,min,max,cur,relsize,levelformat]
  120. min,max = value range of slider
  121. cur = current value
  122. levelformat = string that shows levelformat, example '%2ld'. leave
  123. a large amount of spaces left in lefttext for this.
  124. slideraction(info,cur) {x|y}
  125. example: [SLIDE,0,'Colors:',FALSE,1,8,3,5,'']
  126.  
  127. [STR,action,lefttext,initial,maxchars,relsize]
  128. initial = initial string contents
  129. maxchars = max #of chars for string
  130. stringaction(info,newstring) {x}
  131. example: [STR,0,'Pattern','#?.e',200,5]
  132.  
  133. [TEXT,text,lefttext,borderbool,relsize] {x}
  134. borderbool = whether or not a recessed bevelbox should be placed around 'text'
  135. example: [TEXT,'Selected Fonts',NIL,FALSE,3]
  136.  
  137. *[NUM,int,lefttext,borderbool,relsize] {x}
  138.  
  139. *[RENDER,actionr,actionp,x,y]               -> in fontunits
  140. renderrefresh(x,y,xs,ys)
  141. renderpress(x,y)                            -> relative to topcorner
  142.  
  143. *[RENDERFIXED,actionr,actionp,x,y]          -> in pixels
  144. renderfixedrefresh(x,y)
  145. renderfixedpress(x,y)
  146.  
  147. [SBUTTON] {x}
  148. -> same as button, only now resizes.
  149.  
  150. [BAR], [SPACE] {x,y}, [SPACEH] {x}, [SPACEV] {y}
  151. BAR places a nice divider-bar between gadgets/groups. Whether it's
  152. horizontal or vertical depends on which group it is in. SPACE/SPACEH/SPACEV
  153. do nothing, they only eats up space. This can be very handy in GUI design,
  154. they act like a spring between elements (do not use them on the borders of a
  155. GUI, only in the middle).
  156.  
  157. See the example GUI's how to use these.
  158.  
  159. actioncodes:
  160. - an integer in the range 0..999
  161.   dogui() will close all and exit with this code
  162. - a ptr to a procedure to perform an action. the type of procedure
  163.   (i.e. #of args) differs with each gadget. After calling the procedure,
  164.   dogui() will normally continue with this gui.
  165.  
  166. #?text:
  167. (where #? is left/right etc.): a text to place next to the gadget. often
  168. is allowed to be NIL.
  169.  
  170. relsize,relx,rely:
  171. generally gadgets will automatically get a size depending on a number of
  172. factors, but relsize allows the programmer to give a minimum size for
  173. certain gadgets, thereby sizing a whole group. If other gadgets already
  174. account for the minimum size, this one can safely be set to a low value
  175. such as 2. All these sizes are calculate in terms of the hight of the font.
  176.  
  177. nil_term_elist:
  178. a nil-terminated E list, such as ['One','Two','Three',NIL]
  179.  
  180. isvert:
  181. TRUE if gadget needs to be vertical, horizontal by default.
  182.  
  183.  
  184. exceptions raised:
  185.  
  186. "MEM"   -- no mem
  187. "GUI"   -- for things like CreateGadgetA, OpenWindowTagList etc.
  188. "GT"    -- couldn't open gadtools.library
  189. "DF"    -- same for diskfont
  190. "bigg"    -- for "BIG Gui": interface is calculated to be bigger than the screen.
  191.        generally you should keep gui's small, so that they still fit on
  192.        640x200 topaz screens. If the user runs Times/30 on this screen, he
  193.        has a problem.
  194. "Egui"  -- a design error: most probably handed over a list to dogui()
  195.            that was either to long or too short
  196. <other> -- Raise()ed by own function
  197.  
  198.  
  199. example of usage of other three function (= definition easygui())
  200.  
  201.  
  202. PROC easygui(windowtitle,gui,info=NIL,screen=NIL,textattr=NIL) HANDLE
  203.   DEF gh=NIL:PTR TO guihandle,res=-1
  204.   gh:=guiinit(windowtitle,gui,info,screen,textattr)
  205.   WHILE res<0
  206.     Wait(gh.sig)
  207.     res:=guimessage(gh)
  208.   ENDWHILE
  209. EXCEPT DO
  210.   cleangui(gh)
  211.   IF exception THEN ReThrow()
  212. ENDPROC res
  213.  
  214.  
  215. General advice: try out the examples. Sometimes something won't work, but
  216. EasyGUI is flexible enough that at least one way of arranging groups etc.
  217. will give you a nice GUI :-). If you need more power than EasyGUI currently
  218. gives, you'll have to use MUI/BGUI/Triton/WhatEver instead.
  219.  
  220.  
  221.  
  222. biggest known bugs:
  223. - sets gadgets to origanal values on resize (!).
  224.